Hermes Agent 完整配置教程
Hermes Agent 完整配置教程
来源：htmlDecode("及时体育")
原文链接：https://mp.weixin.qq.com/s/bh-qQcvQ2eOcOWcP7olGTw
tags: Hermes AI-Agent 配置教程 Nous-Research created: 2026-04-10
Hermes Agent 完整配置教程
Hermes Agent 是 Nous Research 开发的开源 AI 智能体框架，可在终端、消息平台（Telegram/Discord/Slack 等）和 IDE 中运行。支持任意 LLM 提供商（OpenRouter、Anthropic、OpenAI、本地模型等 18+ 提供商）。
安装与初始化
# 一键安装
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
# 交互式初始设置向导
hermes setup
# 查看健康状态
hermes doctor
# 启动交互聊天
hermes
目录结构
所有配置和文件都在 ~/.hermes/ 目录下：
~/.hermes/
├── config.yaml # 主配置文件（模型、终端、TTS、压缩等）
├── .env # API 密钥和敏感信息
├── auth.json # OAuth 凭证（Nous Portal 等）
├── SOUL.md # Agent 身份定义（系统提示词第一位）
├── memories/ # 持久记忆（MEMORY.md、USER.md）
├── skills/ # 已安装的技能
├── cron/ # 定时任务
├── sessions/ # 会话记录
└── logs/ # 日志（gateway.log、errors.log，自动脱敏）
Profiles 使用 ~/.hermes/profiles/<名称>/ 目录，结构相同。
配置文件详解 (config.yaml)
使用 hermes config edit 打开编辑，或用 hermes config set KEY VAL 设置。
配置优先级（从高到低）
.env 中的环境变量 config.yaml 中的显式配置 默认值
核心配置段
model — 模型与提供商
model:
default: "anthropic/claude-sonnet-4" # 默认模型
provider: "openrouter" # 提供商
base_url: "" # 自定义端点（优先于 provider）
api_key: "" # 自定义端点的 API Key
context_length: 0 # 0 = 自动检测
agent — Agent 行为
agent:
max_turns: 90 # 单次会话最大工具调用轮数
tool_use_enforcement: true # 强制使用工具
terminal — 终端后端
terminal:
backend: local # local | docker | ssh | modal | singularity | daytona
cwd: "" # 工作目录（默认当前目录）
timeout: 180 # 命令超时秒数
notify_on_complete_threshold: 60 # 超过此秒数的后台任务完成后通知
allowlist: [] # 允许的命令白名单
blocklist: [] # 阻止的命令黑名单
persistent_shell: true # 使用持久 shell（保留环境变量和状态）
** Docker 后端额外配置： **
terminal:
backend: docker
docker:
image: "nousresearch/hermes-agent:latest"
container_name: "hermes-agent"
auto_remove: false
volumes: [] # 挂载卷
network_mode: "" # 网络模式
credential_forwarding: true # 自动转发 Docker 凭证
** SSH 后端额外配置： **
terminal:
backend: ssh
ssh:
host: "" # SSH 主机
port: 22
user: ""
identity_file: "~/.ssh/id_rsa"
** Modal 后端额外配置： **
terminal:
backend: modal
modal:
image: "modal-labs/modal-python:3.11"
secret_names: [] # Modal secrets
timeout: 300
compression — 上下文压缩
compression:
enabled: true
threshold: 0.50 # 上下文使用率达到 50% 时触发
target_ratio: 0.20 # 压缩到原始大小的 20%
model: "" # 空 = 使用主模型，也可单独指定
provider: "" # 空 = 使用主提供商
三个参数如何配合： ** threshold ** ：何时开始压缩 ** target_ratio ** ：压缩到什么程度 threshold 越低、target_ratio 越小 = 压缩越激进
display — 显示设置
display:
skin: "default" # 主题皮肤
tool_progress: true # 显示工具执行进度
show_reasoning: false # 显示推理过程
show_cost: false # 显示成本
按平台单独覆盖进度显示：
display:
tool_progress:
telegram: false
discord: true
memory — 记忆系统
memory:
memory_enabled: true # 启用持久记忆
user_profile_enabled: true # 启用用户画像记忆
provider: "" # 空 = 内置记忆系统
# 可选: honcho, mem0, openviking, hindsight 等
security — 安全
security:
tirith_enabled: true # 启用 Tirith 安全检查
website_blocklist:
enabled: false
domains: # 阻止的域名
- "*.internal.company.com"
- "admin.example.com"
shared_files: # 外部规则文件
- "/etc/hermes/blocked-sites.txt"
approvals — 命令审批
approvals:
mode: manual # manual | smart | off
模式 说明 manual （默认） 执行危险命令前询问用户 smart 用辅助 LLM 自动判断风险，低风险自动通过 off 跳过所有安全检查（等同于 HERMES_YOLO_MODE=true ）
checkpoints — 检查点
checkpoints:
enabled: true # 破坏性文件操作前自动快照
max_snapshots: 50 # 每个目录最多保留的检查点数
delegation — 子代理
delegation:
# model: "" # 覆盖子代理模型（空 = 继承父级）
# provider: "" # 覆盖子代理提供商
# base_url: "" # 直接指定 OpenAI 兼容端点
# api_key: "" # 端点的 API Key
优先级： delegation.base_url > delegation.provider > 继承父级
clarify — 澄清超时
clarify:
timeout: 120 # 等待用户澄清的秒数
smart_model_routing — 智能模型路由
smart_model_routing:
enabled: true
max_simple_chars: 160
max_simple_words: 28
cheap_model:
provider: openrouter
model: google/gemini-2.5-flash
短小简单的请求自动走便宜模型，复杂任务走主模型。
streaming — 流式输出
streaming:
enabled: true
gateway: true # 网关流式（Telegram/Discord/Slack）
cli: true # CLI 流式
human_delay — 人为延迟
human_delay:
enabled: false
min_seconds: 1
max_seconds: 5
让消息发送更自然，不显得像机器秒回。
timezone — 时区
timezone: "Asia/Shanghai" # 设置时区
code_execution — 代码执行
code_execution:
enabled: true
timeout: 300 # Python 脚本超时秒数
web_search — 网页搜索
web_search:
backend: "firecrawl" # firecrawl | duckduckgo | google | searxng
firecrawl_api_key: ""
firecrawl_api_url: "" # 自建 Firecrawl 地址
browser — 浏览器自动化
browser:
backend: "local" # local | browserbase | browseruse | camofox
# Browserbase 配置
browserbase_api_key: ""
browserbase_project_id: ""
tts — 文字转语音
tts:
provider: "edge" # edge（免费默认）| elevenlabs | openai | kokoro | fish
elevenlabs_api_key: ""
voice: "" # 声音名称
stt — 语音转文字
stt:
enabled: true
provider: local # local（faster-whisper）| groq | openai
local:
model: base # tiny | base | small | medium | large-v3
privacy — 隐私
privacy:
redact_secrets: true # 日志自动脱敏
reasoning_effort — 推理力度
reasoning_effort: "medium" # none | minimal | low | medium | high | xhigh
环境变量 (.env)
位于 ~/.hermes/.env ，存放所有 API 密钥。
主要提供商密钥
环境变量 用途 OPENROUTER_API_KEY OpenRouter ANTHROPIC_API_KEY Anthropic (Claude) DEEPSEEK_API_KEY DeepSeek HF_TOKEN Hugging Face GLM_API_KEY z.ai / GLM KIMI_API_KEY Kimi / Moonshot MINIMAX_API_KEY MiniMax DASHSCOPE_API_KEY 阿里云 / DashScope COPILOT_GITHUB_TOKEN GitHub Copilot KILOCODE_API_KEY Kilo Code OPENCODE_ZEN_API_KEY OpenCode Zen OPENCODE_GO_API_KEY OpenCode Go AI_GATEWAY_API_KEY AI Gateway
可选功能密钥
环境变量 用途 FIRECRAWL_API_KEY 网页搜索/抓取 FIRECRAWL_API_URL 自建 Firecrawl 地址 BROWSERBASE_API_KEY 浏览器自动化 BROWSERBASE_PROJECT_ID Browserbase 项目 ID FAL_KEY 图像生成 (FLUX) ELEVENLABS_API_KEY ElevenLabs TTS VOICE_TOOLS_OPENAI_KEY OpenAI TTS + 语音转录 GROQ_API_KEY Groq Whisper (免费 STT) HONCHO_API_KEY Honcho 记忆后端 SUPERMEMORY_API_KEY Supermemory 记忆后端 TINKER_API_KEY RL 训练 WANDB_API_KEY Weights & Biases
AI 提供商配置
快速设置
# 交互式选择提供商和模型
hermes model
# 设置向导（可选 section: model|terminal|gateway|tools|agent）
hermes setup
# 查看当前配置
hermes config
支持的提供商一览
提供商 认证方式 说明 ** Nous Portal ** OAuth ( hermes login --provider nous ) Nous 官方订阅服务 ** OpenAI Codex ** OAuth ( hermes login --provider openai-codex ) ChatGPT OAuth ** GitHub Copilot ** OAuth / Token 需 GitHub 账号 ** Anthropic ** API Key 或 Claude Code OAuth Claude Pro/Max ** OpenRouter ** OPENROUTER_API_KEY 默认推荐，模型最多 ** DeepSeek ** DEEPSEEK_API_KEY 性价比高 ** z.ai / GLM ** GLM_API_KEY 智谱 AI ** Kimi / Moonshot ** KIMI_API_KEY 月之暗面 ** MiniMax ** MINIMAX_API_KEY MiniMax ** 阿里云 ** DASHSCOPE_API_KEY 通义千问 ** Hugging Face ** HF_TOKEN 开源模型 ** Google / Gemini ** GOOGLE_API_KEY Gemini ** xAI / Grok ** XAI_API_KEY Grok ** OpenAI ** OPENAI_API_KEY GPT 系列 ** Azure OpenAI ** 自定义端点 企业版 ** Ollama ** 本地 (localhost:11434) 零配置本地模型 ** vLLM ** 自定义端点 高性能 GPU 服务 ** 自定义端点 ** config.yaml 配置 任何 OpenAI 兼容 API
本地模型配置
** Ollama（零配置）： **
model:
default: "ollama/qwen2.5:32b"
base_url: "http://localhost:11434/v1"
api_key: "ollama"
context_length: 32768
** vLLM： **
model:
default: "vllm/meta-llama/Llama-3.1-70B-Instruct"
base_url: "http://localhost:8000/v1"
api_key: "vllm"
context_length: 32768
OpenRouter 路由配置
provider_routing:
sort: "throughput" # "price"（默认）| "throughput" | "latency"
# only: ["anthropic"] # 只用这些提供商
# ignore: ["deepinfra"] # 跳过这些提供商
# order: ["anthropic", "google"] # 按此顺序尝试
# data_collection: "deny" # 排除可能存储/训练数据的提供商
快捷方式：模型名加 :nitro = 按吞吐量排序，加 :floor = 按价格排序。
备用模型 (Fallback)
fallback_model:
provider: openrouter
model: anthropic/claude-sonnet-4
# base_url: "" # 自定义端点
# api_key_env: "" # 自定义端点的 API Key 环境变量名
主模型失败时自动切换，每会话最多触发一次。
自定义/命名端点
model:
custom_providers:
local:
name: "本地 Ollama"
base_url: "http://localhost:11434/v1"
api_key: "ollama"
api_mode: openai
work:
name: "公司代理"
base_url: ""
api_key: "secret-key"
api_mode: openai
会话中切换： /model custom:local:qwen-2.5
终端后端配置
后端类型对比
后端 适用场景 隔离性 local 本地开发，直接访问系统 无 docker 需要环境隔离 容器级 ssh 远程服务器 远程机器 modal Serverless GPU 云端隔离 singularity HPC 集群 容器级 daytona 云端沙箱 云端隔离
Docker 凭证自动转发
terminal:
backend: docker
docker:
credential_forwarding: true # 自动转发 Docker Hub、GHCR 等凭证
持久 Shell
terminal:
persistent_shell: true # 保留环境变量、cd 状态等
消息网关 (Messaging Gateway)
启动与管理
hermes gateway # 前台运行
hermes gateway setup # 交互式配置各平台
hermes gateway install # 安装为用户服务
sudo hermes gateway install --system # Linux 开机自启系统服务
hermes gateway start # 启动
hermes gateway stop # 停止
hermes gateway status # 状态
支持的平台
平台 语音 图片 文件 线程 流式 Telegram ✅ ✅ ✅ ✅ ✅ Discord ✅ ✅ ✅ ✅ ✅ Slack ✅ ✅ ✅ ✅ ✅ WhatsApp — ✅ ✅ — ✅ Signal — ✅ ✅ — ✅ Email — ✅ ✅ ✅ — Matrix ✅ ✅ ✅ ✅ ✅ 企业微信 (WeCom) ✅ ✅ ✅ — ✅ 飞书 (Feishu) ✅ ✅ ✅ ✅ ✅
安全配置
** 推荐：白名单模式 **
# 在 .env 中
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
** DM 配对模式（免配置 ID）： ** 未知用户 DM 时收到一次性配对码，管理员批准后才能使用：
hermes pairing approve telegram XKGH5N7P
hermes pairing list # 查看待审批
hermes pairing revoke telegram XKGH5N7P # 撤销
会话重置策略
// ~/.hermes/gateway.json
{
"reset_by_platform" : {
"telegram" : { "mode" : "idle" , "idle_minutes" : 240 },
"discord" : { "mode" : "idle" , "idle_minutes" : 60 }
}
}
策略 默认 说明 daily 4:00 AM 每天固定时间重置 idle 1440 分钟 空闲 N 分钟后重置 both 组合 任一条件触发即重置
工具集 (Toolsets)
hermes tools # 交互式启用/禁用
hermes tools list # 列出所有工具集
hermes tools enable NAME # 启用
hermes tools disable NAME # 禁用
工具集 功能 web 网页搜索与内容提取 browser 浏览器自动化 terminal Shell 命令执行 file 文件读写/搜索/补丁 code_execution 沙箱 Python 执行 vision 图像分析 image_gen AI 图像生成 tts 文字转语音 skills 技能浏览与管理 memory 持久记忆 session_search 搜索历史对话 delegation 子代理任务分发 cronjob 定时任务管理 clarify 向用户提问澄清
⚠️ 工具集变更后需要 /reset 开启新会话才能生效，以保护提示词缓存。
技能系统 (Skills)
hermes skills list # 查看已安装技能
hermes skills browse # 浏览技能市场
hermes skills search QUERY # 搜索
hermes skills install ID # 安装
hermes skills config # 按平台启用/禁用
hermes skills check # 检查更新
hermes skills update # 更新过时技能
hermes skills tap add REPO # 添加 GitHub 仓库作为技能源
会话中加载技能： /skill 名称 或启动时预加载： hermes -s 名称
技能遵循渐进式披露模式，只在需要时加载，最小化 token 消耗。
记忆系统 (Memory)
内置记忆
Hermes 默认使用基于文件的记忆系统： memories/MEMORY.md — 长期记忆（Agent 自行管理） memories/USER.md — 用户画像 每日日志 memory/YYYY-MM-DD.md
外部记忆后端
支持 Honcho、Mem0、OpenViking、Hindsight、Holographic、RetainDB、ByteRover 等。
hermes memory setup # 配置记忆提供商
hermes honcho setup # 配置 Honcho
MCP 服务器集成
hermes mcp serve # 将 Hermes 作为 MCP 服务器运行
hermes mcp add NAME --url URL # 添加 HTTP 传输的 MCP 服务器
hermes mcp add NAME -- command CMD # 添加 stdio 传输的 MCP 服务器
hermes mcp remove NAME # 移除
hermes mcp list # 列出已配置
hermes mcp test NAME # 测试连接
hermes mcp configure NAME # 按工具筛选
MCP 服务器支持 stdio 和 HTTP 两种传输方式，可接入 GitHub、数据库、文件系统等外部工具。
多实例配置 (Profiles)
运行多个独立的 Hermes 实例，各自有独立的配置、会话、技能和记忆。
hermes profile list # 列出所有 Profile
hermes profile create NAME # 创建（--clone 克隆当前，--clone-all 克隆全部）
hermes profile use NAME # 设为默认
hermes profile delete NAME # 删除
hermes profile show NAME # 查看详情
hermes profile export NAME # 导出为 tar.gz
hermes profile import FILE # 从归档导入
使用： hermes -p 名称 或 hermes profile use 名称 设为默认后直接用 hermes 。
定时任务 (Cron)
hermes cron list # 列出任务
hermes cron create "30m" # 每 30 分钟
hermes cron create "0 9 * * *" # 每天 9:00
hermes cron edit ID # 编辑
hermes cron pause ID # 暂停
hermes cron resume ID # 恢复
hermes cron run ID # 立即触发
hermes cron remove ID # 删除
任务可关联技能、指定投递目标（消息平台/本地文件）、设置执行次数。
语音配置 (STT/TTS)
语音转文字 (STT)
消息平台的语音消息自动转录。 提供商 费用 配置 faster-whisper（本地） 免费 pip install faster-whisper Groq Whisper 免费额度 设置 GROQ_API_KEY OpenAI Whisper 付费 设置 VOICE_TOOLS_OPENAI_KEY
stt:
enabled: true
provider: local
local:
model: base # tiny | base | small | medium | large-v3
文字转语音 (TTS)
提供商 环境变量 免费 Edge TTS 无需配置 ✅ 默认 ElevenLabs ELEVENLABS_API_KEY 免费额度 OpenAI VOICE_TOOLS_OPENAI_KEY 付费 Kokoro（本地） 无需配置 ✅ Fish Audio FISH_AUDIO_API_KEY 免费额度
语音命令： /voice on — 语音到语音 /voice tts — 始终输出语音 /voice off — 关闭
安全与审批
Tirith 安全检查
security:
tirith_enabled: true # 启用终端命令安全检查
命令审批模式
approvals:
mode: manual # manual | smart | off
manual ：每个可疑命令都需用户确认 smart ：辅助 LLM 判断风险，低风险自动放行 off ：完全跳过（危险！仅限沙箱环境）
CLI 快捷模式： hermes --yolo 跳过所有审批。
网站黑名单
security:
website_blocklist:
enabled: true
domains:
- "*.internal.company.com"
- "admin.example.com"
支持精确域名、通配子域名（ .xxx ）、TLD 通配（ .local ）。
上下文压缩
当对话接近 token 限制时自动压缩：
compression:
enabled: true
threshold: 0.50 # 50% 时触发
target_ratio: 0.20 # 压缩到 20%
也可配置独立的压缩模型（用便宜模型做压缩节省成本）：
compression:
model: "google/gemini-2.5-flash"
provider: "openrouter"
常用命令速查
CLI 全局参数
hermes # 交互聊天（默认）
hermes -q "问题" # 单次查询
hermes -c # 继续上次会话
hermes -r SESSION_ID # 恢复指定会话
hermes -w # git worktree 隔离模式
hermes -s 技能名 # 预加载技能
hermes -p 配置名 # 使用指定 Profile
hermes --yolo # 跳过危险命令审批
会话内斜杠命令
命令 功能 /new 新会话 /model [提供商:模型] 查看/切换模型 /config 查看配置 /provider 查看提供商信息 /tools 管理工具集 /skills 搜索/安装技能 /skill 名称 加载技能到当前会话 /cron 管理定时任务 /voice on|off|tts 语音模式 /yolo 切换审批绕过 /usage Token 用量 /rollback [N] 回滚文件检查点 /retry 重发最后一条消息 /undo 删除最后一条对话 /compress 手动压缩上下文 /reload-mcp 重载 MCP 服务器 /help 帮助 /quit 退出
配置管理
hermes config # 查看当前配置
hermes config edit # 编辑 config.yaml
hermes config set KEY VAL # 设置单个值
hermes config path # 打印配置文件路径
hermes config env-path # 打印 .env 路径
hermes config check # 检查缺失/过时的配置项
hermes config migrate # 用新配置选项更新
hermes doctor [--fix] # 检查依赖和配置
故障排查
模型/提供商问题
hermes doctor # 检查配置和依赖
hermes login # 重新认证 OAuth 提供商
# 检查 .env 是否有正确的 API Key
工具不可用
hermes tools — 检查工具集是否对当前平台启用 某些工具需要环境变量（检查 .env ） /reset 开始新会话后生效
语音不工作
检查 stt.enabled: true 确认提供商： pip install faster-whisper 或设置 API Key 重启网关
技能不显示
hermes skills list — 确认已安装 hermes skills config — 检查平台启用状态 显式加载： /skill 名称 或 hermes -s 名称
网关问题
grep -i "failed to send|error" ~/.hermes/logs/gateway.log | tail -20
更改不生效
更改类型 生效方式 工具/技能 /reset 开始新会话 网关配置 /restart 重载网关 代码修改 重启 CLI 或网关进程